---
title: Match highlight plugin
---

import Install from '../../../../components/Install.astro'


The plugin-match-highlight plugin allows Orama to keep track of all token positions on each property of each document.

## Installation

You can install the plugin using any major Node.js package manager:

<Install pkg="@orama/plugin-match-highlight" />

## Usage

Plugin usage depends on the runtime that you are using, even though the goal is to expose the exact same APIs for browsers, Deno, and all the other JavaScript engines.

The plugin exports `afterInsertHook`, which will be the hook used by Orama to add positions, and `searchWithHighlight` which wraps the original Orama's `search` function to return positions alongside docs.

```typescript copy
import { create, insert } from "@orama/orama";
import {
  afterInsert as highlightAfterInsert,
  searchWithHighlight,
} from "@orama/plugin-match-highlight";

// Create a new Orama instance
const db = await create({
  schema: {
    text: "string",
  },
  plugins: [
    // Register the hook
    {
      name: "highlight",
      afterInsert: highlightAfterInsert,
    },
  ],
});

// Insert a document
await insert(db, { text: "hello world" });

// Use the plugin's searchWithHighlight function to query the database
const results = await searchWithHighlight(db, { term: "hello" });
```

This will add the `positions` property to each `hit`:

```js copy
{
  elapsed: {...},
  count: ...,
  hits: [
    {
      id: ...,
      score: ...,
      document: { text: 'hello world' },
      positions: {
        text: {
          hello: [
            {
              start: 0,
              length: 5
            }
          ]
        }
      }
    }
  ]
}
```

# Saving Database State with Highlights

Orama exposes a `save` method, which is used to persist its state either in-memory or on disk. \
By default, it doesn't save the highlights exposed by this plugin. If you need them, you can easily handle this case by using the `saveWithHighlight` and `loadWithHighlight` functions:

```js
import { create, insert } from "@orama/orama";
import {
  afterInsert as highlightAfterInsert,
  saveWithHighlight,
  loadWithHighlight,
} from "@orama/plugin-match-highlight";

const db = await create({
  schema: {
    text: "string",
  },
  plugins: [
    // Register the hook
    {
      name: "highlight",
      afterInsert: highlightAfterInsert,
    },
  ],
});

await insert(db, { text: "hello world" });

const savedDB = await saveWithHighlight(db);

const restoredDB = await loadWithHighlight(savedDB);
```

# CommonJS Imports

Orama plugins ship **ESM** modules by default. This allows us to move faster when providing new features and bug fixes, as well as using the `"exports"` field in `package.json` to provide a better developer experience.

CommonJS imports are still supported, but we suggest you to migrate to ESM.

## TypeScript

Set `moduleResolution` in the `compilerOptions` in your `tsconfig.json` to be either `Node16` or `NodeNext`.

When importing types, always refer to the standard import:

```ts copy
import { searchWithHighlight } from "@orama/plugin-match-highlight";
```
